<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, user-scalable=no">
  <meta name="generator" content="made with love by dartdoc 6.2.2">
  <meta name="description" content="flutter_contacts API docs, for the Dart programming language.">
  <title>flutter_contacts - Dart API docs</title>


  
  <link rel="preconnect" href="https://fonts.gstatic.com">
  <link href="https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,300;0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@48,400,0,0" rel="stylesheet">
  
  <link rel="stylesheet" href="static-assets/github.css?v1">
  <link rel="stylesheet" href="static-assets/styles.css?v1">
  <link rel="icon" href="static-assets/favicon.png?v1">

  
</head>


<body data-base-href="" data-using-base-href="false" class="light-theme">

<div id="overlay-under-drawer"></div>

<header id="title">
  <span id="sidenav-left-toggle" class="material-symbols-outlined" role="button" tabindex="0">menu</span>
  <ol class="breadcrumbs gt-separated dark hidden-xs">
    <li><a href="https://github.com/QuisApp/flutter_contacts">flutter_contacts package</a></li>
  </ol>
  <div class="self-name">flutter_contacts</div>
  <form class="search navbar-right" role="search">
    <input type="text" id="search-box" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search...">
  </form>
  <div class="toggle" id="theme-button">
    <label for="theme">
      <input type="checkbox" id="theme" value="light-theme">
      <span id="dark-theme-button" class="material-symbols-outlined">
        brightness_4
      </span>
      <span id="light-theme-button" class="material-symbols-outlined">
        brightness_5
      </span>
    </label>
  </div>
</header>
<main>

  <div id="dartdoc-main-content" class="main-content">
      
<section class="desc markdown">
  <h1 id="flutter_contacts">flutter_contacts</h1>
<p><a href="https://pub.dev/packages/flutter_contacts"><img src="https://img.shields.io/pub/v/flutter_contacts?label=version" alt="pub"></a>
<a href="https://pub.dev/packages/flutter_contacts/score"><img src="https://img.shields.io/pub/points/flutter_contacts" alt="pub points"></a>
<a href="https://pub.dev/packages/flutter_contacts/score"><img src="https://img.shields.io/pub/popularity/flutter_contacts" alt="popularity"></a>
<a href="https://pub.dev/packages/flutter_contacts/score"><img src="https://img.shields.io/pub/likes/flutter_contacts" alt="likes"></a></p>
<p>Flutter plugin to read, create, update, delete and observe native contacts on Android and iOS, with group support, vCard support, and contact permission handling.</p>
<p>For a minimalistic example, take a look at <a href="https://github.com/QuisApp/flutter_contacts/blob/master/example"><code>example/</code></a>. You can write a full-fledged contacts app with it – see <a href="https://github.com/QuisApp/flutter_contacts/blob/master/example_full"><code>example_full/</code></a> to see how.</p>
<h2 id="quick-start">Quick start</h2>
<pre class="language-dart"><code class="language-dart">// See installation notes below regarding AndroidManifest.xml and Info.plist
import 'package:flutter_contacts/flutter_contacts.dart';

// Request contact permission
if (await FlutterContacts.requestPermission()) {
  // Get all contacts (lightly fetched)
  List&lt;Contact&gt; contacts = await FlutterContacts.getContacts();

  // Get all contacts (fully fetched)
  contacts = await FlutterContacts.getContacts(
      withProperties: true, withPhoto: true);

  // Get contact with specific ID (fully fetched)
  Contact contact = await FlutterContacts.getContact(contacts.first.id);

  // Insert new contact
  final newContact = Contact()
    ..name.first = 'John'
    ..name.last = 'Smith'
    ..phones = [Phone('555-123-4567')];
  await newContact.insert();

  // Update contact
  contact.name.first = 'Bob';
  await contact.update();

  // Delete contact
  await contact.delete();

  // Open external contact app to view/edit/pick/insert contacts.
  await FlutterContacts.openExternalView(contact.id);
  await FlutterContacts.openExternalEdit(contact.id);
  final contact = await FlutterContacts.openExternalPick();
  final contact = await FlutterContacts.openExternalInsert();

  // Listen to contact database changes
  FlutterContacts.addListener(() =&gt; print('Contact DB changed'));

  // Create a new group (iOS) / label (Android).
  await FlutterContacts.insertGroup(Group('', 'Coworkers'));

  // Export contact to vCard
  String vCard = contact.toVCard();

  // Import contact from vCard
  contact = Contact.fromVCard('BEGIN:VCARD\n'
      'VERSION:3.0\n'
      'N:;Joe;;;\n'
      'TEL;TYPE=HOME:123456\n'
      'END:VCARD');
}
</code></pre>
<h2 id="simplified-contact-model">Simplified contact model</h2>
<p>See <a href="https://github.com/QuisApp/flutter_contacts/blob/master/lib/contact.dart">code</a> for complete data model.</p>
<pre class="language-dart"><code class="language-dart">class Contact {
    String id;
    String displayName;
    Uint8List? photo;
    Uint8List? thumbnail;
    Name name;
    List&lt;Phone&gt; phones;
    List&lt;Email&gt; emails;
    List&lt;Address&gt; addresses;
    List&lt;Organization&gt; organizations;
    List&lt;Website&gt; websites;
    List&lt;SocialMedia&gt; socialMedias;
    List&lt;Event&gt; events;
    List&lt;Note&gt; notes;
    List&lt;Group&gt; groups;
}
class Name { String first; String last; }
class Phone { String number; PhoneLabel label; }
class Email { String address; EmailLabel label; }
class Address { String address; AddressLabel label; }
class Organization { String company; String title; }
class Website { String url; WebsiteLabel label; }
class SocialMedia { String userName; SocialMediaLabel label; }
class Event { int? year; int month; int day; EventLabel label; }
class Note { String note; }
class Group { String id; String name; }
</code></pre>
<h2 id="demo">Demo</h2>
<p><img src="https://user-images.githubusercontent.com/1289004/101141809-ab165c00-35c9-11eb-90ff-b10318b13f16.gif" alt="demo"></p>
<h2 id="installation">Installation</h2>
<ol>
<li>Add the following key/value pair to your app's <code>Info.plist</code> (for iOS):
<pre class="language-xml"><code class="language-xml">&lt;plist version="1.0"&gt;
&lt;dict&gt;
    ...
    &lt;key&gt;NSContactsUsageDescription&lt;/key&gt;
    &lt;string&gt;Reason we need access to the contact list&lt;/string&gt;
&lt;/dict&gt;
&lt;/plist&gt;
</code></pre>
</li>
<li>Add the following <code>&lt;uses-permissions&gt;</code> tags to your app's <code>AndroidManifest.xml</code> (for
Android):
<pre class="language-xml"><code class="language-xml">&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android" ...&gt;
    &lt;uses-permission android:name="android.permission.READ_CONTACTS"/&gt;
    &lt;uses-permission android:name="android.permission.WRITE_CONTACTS"/&gt;
    &lt;application ...&gt;
    ...
</code></pre>
</li>
</ol>
<h2 id="notes">Notes</h2>
<ul>
<li>On iOS13+ you can only access notes if your app is
<a href="https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_contacts_notes">entitled by Apple</a>
so notes are disabled by default. If you get entitlement, enable them via
<pre class="language-dart"><code class="language-dart">FlutterContacts.config.includeNotesOnIos13AndAbove = true;
</code></pre>
</li>
<li>On both iOS and Android there is a concept of <strong>raw</strong> and <strong>unified</strong> contacts. A
single person might have two raw contacts (for example from Gmail and from iCloud) but
will be merged into a single view called a unified contact. In a contact app you
typically want unified contacts, so this is what's returned by default. You can get
raw contacts instead via
<pre class="language-dart"><code class="language-dart">FlutterContacts.config.returnUnifiedContacts = false;
</code></pre>
However, for now, raw contacts cannot be inserted, updated or deleted.</li>
</ul>
<h2 id="feature-requests">Feature requests</h2>
<p>These features have been requested and will be available soon.</p>
<ul>
<li>Read/write custom ringtones <a href="https://github.com/QuisApp/flutter_contacts/issues/22">#22</a></li>
<li>Block contacts <a href="https://github.com/QuisApp/flutter_contacts/issues/28">#28</a></li>
<li>Support for contacts stored in SIM card <a href="https://github.com/QuisApp/flutter_contacts/issues/26">#26</a> <a href="https://github.com/QuisApp/flutter_contacts/issues/23">#23</a></li>
<li>More raw account information on Android <a href="https://github.com/QuisApp/flutter_contacts/issues/5">#5</a> <a href="https://github.com/QuisApp/flutter_contacts/issues/8">#8</a></li>
</ul>
</section>


      <section class="summary">
          <h2>Libraries</h2>
        <dl>
          <dt id="account">
  <span class="name"><a href="properties_account/properties_account-library.html">account</a></span> 

</dt>
<dd>
</dd>

          <dt id="address">
  <span class="name"><a href="properties_address/properties_address-library.html">address</a></span> 

</dt>
<dd>
</dd>

          <dt id="config">
  <span class="name"><a href="config/config-library.html">config</a></span> 

</dt>
<dd>
</dd>

          <dt id="contact">
  <span class="name"><a href="contact/contact-library.html">contact</a></span> 

</dt>
<dd>
</dd>

          <dt id="diacritics">
  <span class="name"><a href="diacritics/diacritics-library.html">diacritics</a></span> 

</dt>
<dd>
</dd>

          <dt id="email">
  <span class="name"><a href="properties_email/properties_email-library.html">email</a></span> 

</dt>
<dd>
</dd>

          <dt id="event">
  <span class="name"><a href="properties_event/properties_event-library.html">event</a></span> 

</dt>
<dd>
</dd>

          <dt id="flutter_contacts">
  <span class="name"><a href="flutter_contacts/flutter_contacts-library.html">flutter_contacts</a></span> 

</dt>
<dd>
</dd>

          <dt id="group">
  <span class="name"><a href="properties_group/properties_group-library.html">group</a></span> 

</dt>
<dd>
</dd>

          <dt id="name">
  <span class="name"><a href="properties_name/properties_name-library.html">name</a></span> 

</dt>
<dd>
</dd>

          <dt id="note">
  <span class="name"><a href="properties_note/properties_note-library.html">note</a></span> 

</dt>
<dd>
</dd>

          <dt id="organization">
  <span class="name"><a href="properties_organization/properties_organization-library.html">organization</a></span> 

</dt>
<dd>
</dd>

          <dt id="phone">
  <span class="name"><a href="properties_phone/properties_phone-library.html">phone</a></span> 

</dt>
<dd>
</dd>

          <dt id="social_media">
  <span class="name"><a href="properties_social_media/properties_social_media-library.html">social_media</a></span> 

</dt>
<dd>
</dd>

          <dt id="vcard">
  <span class="name"><a href="vcard/vcard-library.html">vcard</a></span> 

</dt>
<dd>
</dd>

          <dt id="website">
  <span class="name"><a href="properties_website/properties_website-library.html">website</a></span> 

</dt>
<dd>
</dd>

        </dl>
      </section>

  </div> <!-- /.main-content -->

  <div id="dartdoc-sidebar-left" class="sidebar sidebar-offcanvas-left">
    <header id="header-search-sidebar" class="hidden-l">
  <form class="search-sidebar" role="search">
    <input type="text" id="search-sidebar" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search...">
  </form>
</header>

<ol class="breadcrumbs gt-separated dark hidden-l" id="sidebar-nav">
  <li><a href="https://github.com/QuisApp/flutter_contacts">flutter_contacts package</a></li>
</ol>


    <h5 class="hidden-xs"><span class="package-name">flutter_contacts</span> <span class="package-kind">package</span></h5>
    <ol>
      <li class="section-title">Libraries</li>
      <li><a href="properties_account/properties_account-library.html">account</a></li>
      <li><a href="properties_address/properties_address-library.html">address</a></li>
      <li><a href="config/config-library.html">config</a></li>
      <li><a href="contact/contact-library.html">contact</a></li>
      <li><a href="diacritics/diacritics-library.html">diacritics</a></li>
      <li><a href="properties_email/properties_email-library.html">email</a></li>
      <li><a href="properties_event/properties_event-library.html">event</a></li>
      <li><a href="flutter_contacts/flutter_contacts-library.html">flutter_contacts</a></li>
      <li><a href="properties_group/properties_group-library.html">group</a></li>
      <li><a href="properties_name/properties_name-library.html">name</a></li>
      <li><a href="properties_note/properties_note-library.html">note</a></li>
      <li><a href="properties_organization/properties_organization-library.html">organization</a></li>
      <li><a href="properties_phone/properties_phone-library.html">phone</a></li>
      <li><a href="properties_social_media/properties_social_media-library.html">social_media</a></li>
      <li><a href="vcard/vcard-library.html">vcard</a></li>
      <li><a href="properties_website/properties_website-library.html">website</a></li>
</ol>

  </div>

  <div id="dartdoc-sidebar-right" class="sidebar sidebar-offcanvas-right">
  </div>

</main>

<footer>
  <span class="no-break">
    flutter_contacts
      1.1.7+1
  </span>

  
</footer>



<script src="static-assets/highlight.pack.js?v1"></script>
<script src="static-assets/docs.dart.js"></script>



</body>

</html>

